List Location Occupancies
Returns a list of LocationOccupancy objects for the warehouse specified by an id path parameter, across
all merchants. Each object is one interval during which a location held inventory of one merchant’s
product.
Intervals are recorded asynchronously, about 40 minutes after inventory moves. meta.projected_through is the UTC
instant up to which recorded intervals are complete; occupancy changes after it may not be reflected yet. It is
read before the intervals, so a result for a period that ends at or before it is final, except that an open
interval can still close (see the sort parameter).
Intervals before occupancy tracking began, at meta.tracking_started_at, are not available: locations
already occupied at that time have intervals with open_reason backfill that start when tracking began.
A client user’s token returns only its own merchant’s intervals, in the merchant’s allowed warehouses and
in any other warehouse where the merchant has intervals. A staff user’s token is limited to the
warehouses and merchants of the user’s group. A warehouse outside the caller’s scope returns 404. A
caller limited to certain merchants receives location as a reference only, and fields:location
returns 400, because the location may now hold another merchant’s inventory.
Authorizations
Generate a JWT access token through a Custom Global Integration and provide it with each request in the Authorization header prefixed with "Bearer" and then a single space.
Path Parameters
The id of the referenced Warehouse.
Query Parameters
Specify additional fields of the Location object to be included in the response.
basic, all, label, priority, qty_on_hand, qty_putaway, qty_unreserved, qty_reserved, qty_locked, is_temp, is_pickable, is_type_auto, created_at, updated_at, last_cyclecount_at, tags, lot, product, rack, slot_type Specify additional fields of the Merchant object to be included in the response. See the selecting fields page for more information.
basic, all, code, name, status, created_at, updated_at, brands, default_brand, custom_fields Specify additional fields of the Product or Packaging* object to be included in the response.
basic, all, created_at, updated_at, container_options, supplies_options, data_collection_options, instruction_options, infill_options, vendor_sku, manufacturer_part_number, unit_level, external_id, barcodes, goods_type, is_available, is_visible, weight, dimensions, volume, inventory, export, regulated_goods, packaging, custom_fields Specify additional fields of the SlotType object to be included in the response.
basic, all, name, is_pickable, sort_order, patterns, is_fixed_capacity, slot_dimensions, weight_capacity, trigger_doi_days, target_doi_days, created_at, updated_at Specify additional fields of the Warehouse object to be included in the response.
basic, all, id, name, is_active, abbreviation Using the filtering syntax, you may filter the results using the following fields:
idmerchant_idproduct_id— one product (only the basic syntax /eqoperator); only with theoccupied_atsortsku— the current SKU of one product (only the basic syntax /eqoperator); also matches intervals that opened under an earlier SKU of the same product. A SKU shared by several merchants' products returns400; filter byproduct_idinstead. Only with theoccupied_atsort.location_id— one location (only the basic syntax /eqoperator); also matches intervals of deleted locations. Only with theoccupied_atsort.is_open—trueorfalse(only the basic syntax /eqoperator);is_open:truerequiressort=vacated_atunless aproduct_id,skuorlocation_idfilter is also givenoccupied_atvacated_at— use{null:true}for open intervals, with the same sort requirement asis_open:trueupdated_at— only withsort=updated_atorsort=-updated_at
Each filter names one field; a comma-separated list of fields is not supported.
The date-time fields accept ISO 8601 values with the eq, neq, in, nin, from, to, gt, gteq, lt
and lteq operators, and the null operator; other operators return 400. from and to are inclusive. A value
without a time zone offset is UTC. Times are stored with millisecond precision, so an eq value copied from a
response matches that instant.
An interval occupies its location from occupied_at up to, but not including, vacated_at. To select the
intervals that overlap a period from S up to E, combine occupied_at{lt:"E"} with
vacated_at[{null:true},{gt:"S"}] and sort=vacated_at: the read then starts at the open intervals and at S,
and passes over only the intervals vacated since S. With the default occupied_at sort, the same filters
pass over the warehouse's whole history before S to find the intervals that started before it. Inclusive
from/to bounds would also return intervals that only touch the period: those vacated exactly at S or
occupied exactly at E.
The default sort order is descending by occupied_at (sort=-occupied_at), with id breaking ties. Pages are linked with opaque cursors. Use sort=vacated_at to read the intervals that overlap a period (see the filter parameter); open intervals, whose vacated_at is NULL, come first. Filters that select only open intervals (is_open:true or vacated_at{null:true}) require this sort, unless they are combined with a product_id, sku or location_id filter. Use sort=updated_at with an updated_at{gt:...} filter to poll for intervals that opened or closed since a previous request; start each poll from the largest updated_at you received. Only one sort field is supported. The product_id, sku and location_id filters require the occupied_at sort.
Closing an interval sets its vacated_at and updated_at, so these two fields can only be sorted in ascending order. Even then, an open interval that closes while you page forward through the results is returned again, with its vacated_at, on a later page. Deduplicate by id, keeping the row with the latest updated_at. The occupied_at order is never affected. The following fields are available for sorting:
occupied_atvacated_atupdated_at
If specified as 1, the meta.count property of the response will be present and populated with the total count of items
matching the query before any paging is applied. This is not included by default to improve performance in some edge
cases and is not required to perform paging using the next property of the response.
See paging parameters for more information.
0 <= x <= 1A cursor for use in pagination which defines the end of the next page of results, non-inclusive.
For collections sorted by id this is the last id. For other sort orders use the
opaque cursor provided by the previous link and meta.cursor_end of the previous page;
a plain record id is also accepted and resolves to that record's position in the sort order.
See paging parameters for more information on paging.
A cursor for use in pagination which defines the start of the next page of results.
For collections sorted by id this is the starting id. For other sort orders use the
opaque cursor provided by the next link and meta.cursor_start of the previous page;
a plain record id is also accepted and resolves to that record's position in the sort order.
See paging parameters for more information on paging.
A limit on the number of objects to be returned.
1 <= x <= 1000100
Response
A dictionary with a collection property that contains a list of up to limit LocationOccupancy
objects matching the query.
A list of LocationOccupancy objects.
Lists of referenced objects included by specifying optional fields. See the selecting fields page for more information.
True if the collection has more items on the next page. Use the "next" link to retrieve the next page of results.
The resource path for the next page of results if any are expected.
The resource path for the previous page of results if any are expected.
Additional metadata pertaining to the response.